Crate notify

source ·
Expand description

Cross-platform file system notification library

Installation

[dependencies]
notify = "6.1.1"

If you want debounced events (or don’t need them in-order), see notify-debouncer-mini or notify-debouncer-full.

Features

List of compilation features, see below for details

  • serde for serialization of events
  • macos_fsevent enabled by default, for fsevent backend on macos
  • macos_kqueue for kqueue backend on macos
  • crossbeam-channel enabled by default, see below

Serde

Events are serializable via serde if the serde feature is enabled:

notify = { version = "6.1.1", features = ["serde"] }

Crossbeam-Channel & Tokio

By default crossbeam-channel is used internally by notify. Which also allows the Watcher to be sync. This can cause issues when used inside tokio.

You can disable crossbeam-channel, letting notify fallback to std channels via

notify = { version = "6.1.1", default-features = false, features = ["macos_kqueue"] }
// Alternatively macos_fsevent instead of macos_kqueue

Note the macos_kqueue requirement here, otherwise no native backend is available on macos.

Known Problems

Network filesystems

Network mounted filesystems like NFS may not emit any events for notify to listen to. This applies especially to WSL programs watching windows paths (issue #254).

A workaround is the PollWatcher backend.

Docker with Linux on MacOS M1

Docker on macos M1 throws Function not implemented (os error 38). You have to manually use the PollWatcher, as the native backend isn’t available inside the emulation.

MacOS, FSEvents and unowned files

Due to the inner security model of FSEvents (see FileSystemEventSecurity), some events cannot be observed easily when trying to follow files that do not belong to you. In this case, reverting to the pollwatcher can fix the issue, with a slight performance cost.

Editor Behaviour

If you rely on precise events (Write/Delete/Create..), you will notice that the actual events can differ a lot between file editors. Some truncate the file on save, some create a new one and replace the old one. See also this and this issues for example.

Parent folder deletion

If you want to receive an event for a deletion of folder b for the path /a/b/.., you will have to watch its parent /a. See here for more details.

Pseudo Filesystems like /proc, /sys

Some filesystems like /proc and /sys on *nix do not emit change events or use correct file change dates. To circumvent that problem you can use the PollWatcher with the compare_contents option.

Linux: Bad File Descriptor / No space left on device

This may be the case of running into the max-files watched limits of your user or system. (Files also includes folders.) Note that for recursive watched folders each file and folder inside counts towards the limit.

You may increase this limit in linux via

sudo sysctl fs.inotify.max_user_instances=8192 # example number
sudo sysctl fs.inotify.max_user_watches=524288 # example number
sudo sysctl -p

Note that the PollWatcher is not restricted by this limitation, so it may be an alternative if your users can’t increase the limit.

Watching large directories

When watching a very large amount of files, notify may fail to receive all events. For example the linux backend is documented to not be a 100% reliable source. See also issue #412.

Examples

For more examples visit the examples folder in the repository.

use notify::{Watcher, RecommendedWatcher, RecursiveMode, Result};

fn main() -> Result<()> {
    // Automatically select the best implementation for your platform.
    let mut watcher = notify::recommended_watcher(|res| {
        match res {
           Ok(event) => println!("event: {:?}", event),
           Err(e) => println!("watch error: {:?}", e),
        }
    })?;

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch(Path::new("."), RecursiveMode::Recursive)?;

    Ok(())
}

With different configurations

It is possible to create several watchers with different configurations or implementations that all call the same event function. This can accommodate advanced behaviour or work around limits.

      fn event_fn(res: Result<notify::Event>) {
          match res {
             Ok(event) => println!("event: {:?}", event),
             Err(e) => println!("watch error: {:?}", e),
          }
      }

      let mut watcher1 = notify::recommended_watcher(event_fn)?;
      // we will just use the same watcher kind again here
      let mut watcher2 = notify::recommended_watcher(event_fn)?;
      // dropping the watcher1/2 here (no loop etc) will end the program

Re-exports

Modules

  • event
    The Event type and the hierarchical EventKind descriptor.
  • inotify
    Watcher implementation for the inotify Linux API
  • null
    Stub Watcher implementation
  • poll
    Generic Watcher implementation based on polling

Structs

  • Config
    Watcher Backend configuration
  • Error
    Notify error type.

Enums

Traits

  • EventHandler
    The set of requirements for watcher event handling functions.
  • Watcher
    Type that can deliver file activity notifications

Functions

  • recommended_watcher
    Convenience method for creating the RecommendedWatcher for the current platform in immediate mode.

Type Definitions

  • RecommendedWatcher
    The recommended Watcher implementation for the current platform
  • Result
    Type alias to use this library’s Error type in a Result